nHTMLn

2.9

USER’S MANUAL

Visit nHTMLn homepage for updates: www.wot.net/~necroman/nn2.htm

nHTMLn is simple.

You can attach objects called “browsers” to your windows. An attached browser can be ordered to navigate to any document, remote or local. When you no longer need a browser, detach it.

You can use the following functions to control browsers:

stop, refresh, back, forward, home, search

attach, detach

The ‘attach’ function creates a new browser and attaches it to a window. If the browser was created successfully, it is selected as the default browser for subsequent operations.

The ‘detach’ function detaches, hides and destroys a browser specified by the window handle in the input parameter. If the handle is invalid, the default browser gets detached.

Parameter:

The handle of the parent window.

Return values:

E_INVALID_WINDOW

E_FAILED

E_ALREADY_ATTACHED

S_OK

Remarks:

A browser is automatically detached when its parent window closes.

If you attach a browser to a disabled window the user will not be able to scroll or follow hyperlinks.

There is no limit on how many browsers you can attach, however, you cannot attach 2 browsers to the same window.

Examples:

The following code attaches a browser to a picture window and detaches it in 5 seconds.

window -p @test

echo -a $dll(nHTMLn,attach,$window(@test).hwnd)

timer 1 5 echo –a $!dll(nHTMLn,detach,$window(@test).hwnd)

navigate

This function tells the default browser to display a document.

Parameter:

The URL of the document.

Return values:

E_INVALID_WINDOW

E_FAILED

S_OK

Examples:

This code creates a browser and displays the mIRC homepage:

window -p @test

echo -a $dll(nHTMLn,attach,$window(@test).hwnd)

echo -a $dll(nHTMLn,navigate,www.mirc.com)

This code displays the mircscripts.org web board on the desktop:

echo -a $dll(nHTMLn,attach,$window(-1).hwnd)

echo -a $dll(nHTMLn,navigate,www.mircscripts.org/board)

This code displays the Microsoft Word document in the mIRC MDI frame:

echo -a $dll(nHTMLn,attach,$window(-3).hwnd)

echo -a $dll(nHTMLn,navigate,d:\mirc\mytext.doc)

This code writes “Hello World”:

echo -a $dll(nHTMLn,attach,$window(-3).hwnd)

echo -a $dll(nHTMLn,navigate,about:Hello World)

select

This function is used to set the default browser. The default browser is usually called when the window handle in the input parameter is invalid. However, the ‘navigate’, ‘handler’, ‘zoom’ and ‘margins’ functions always use the default browser.

Parameter:

The handle of a window with a browser attached.

Return values:

E_INVALID_WINDOW

S_OK

Example:

This code attaches 4 browsers and displays www.msdn.microsoft.com in one of them:

window -p @test1

window -p @test2

window -p @test3

window -p @test4

echo -a $dll(nHTMLn,attach,$window(@test1).hwnd)

echo -a $dll(nHTMLn,attach,$window(@test2).hwnd)

echo -a $dll(nHTMLn,attach,$window(@test3).hwnd)

echo -a $dll(nHTMLn,attach,$window(@test4).hwnd)

echo -a $dll(nHTMLn,select,$window(@test $+ $$?=”Which of the 4?”).hwnd)

echo -a $dll(nHTMLn,navigate,www.msdn.microsoft.com)

selected

This function returns the handle of window containing the default browser.

Parameter:

Ignored.

Return value:

The handle of the default browser’s parent window.

Remarks:

The returned handle may be invalid if the window was closed.

If you use the ‘select’ function in your event-handling alias, make sure to restore the selection.

Examples

This code navigates to www.wot.net/~necroman/nn2.htm without changing the currently selected browser:

var %old_hwnd = $dll(nHTMLn,selected,0)

window -p @test

echo -a $dll(nHTMLn,attach,$window(@test).hwnd)

echo -a $dll(nHTMLn,navigate,www.wot.net/~necroman/nn2.htm)

echo -a $dll(nHTMLn,select,%old_hwnd)

stop, refresh, back, forward, home, search

These functions perform the same actions Internet Explorer toolbar buttons. For example, the ‘back’ function tells a browser to navigate to the previous document.

Parameter:

The handle of a window with a browser attached. If the handle is invalid, the default browser is used.

Return values:

E_INVALID_WINDOW

E_FAILED

S_OK

margins

This function sets margins, in pixels, for the default browser.

Parameter:

If the first word is a number, it changes all the 4 margins.

If a word begins with the “l”, “r”, “t” or “b” character, the number that follows it changes the left, right, top or bottom margin, respectively.

Return values:

E_INVALID_WINDOW
E_FAILED

E_INVALID_MARGINS

S_OK

Examples

This code sets all the 4 margins to -2, hiding the border around the browser:

window -p @test

echo -a $dll(nHTMLn,attach,$window(@test).hwnd)

echo -a $dll(nHTMLn,margins,-2)

echo -a $dll(nHTMLn,navigate,www.hotornot.com)

You can specify different values for different margins:

echo -a $dll(nHTMLn,attach,$window(Status window).hwnd)

echo -a $dll(nHTMLn,margins,left:45 right:40 top:30 bottom:55)

This code sets the left margin to 10, right to 20, top and bottom to 5:

echo -a $dll(nHTMLn,margins,5,r=20,l=10)

name, url

These functions return the name and URL of the document displayed in a browser.

Parameter:

The handle of a window with a browser attached. If the handle is invalid, the default browser is used.

Return values:

The name or the URL of the document.

E_INVALID_WINDOW

E_FAILED

Examples:

This code updates the titlebar of a picture window with the name of the currently loaded document:

titlebar @test $dll(nHTMLn,name,$window(@test).hwnd)

find, caption

The ‘find’ function returns the handle of a window with a certain caption. The ‘caption’ function returns the caption of a window with a certain handle.

Parameter:

The text (‘find’) or handle (‘caption’) to search for.

Return values:

If the window is not found the return value is E_NOT_FOUND.

Remarks:

The ‘find’ function can be useful when attaching a browser to a dialog control. This function searches ALL windows on the desktop, not only mIRC children. To avoid collisions, make the caption of your dialog control unique and call the ‘find’ function. Once you have got the handle you can restore the original name of your control.

Examples:

This code obtains the window handle of a dialog control and attaches a browser to it:

…

box “ThisIsMyLameBox”, 10, 5 5 200 200

…

var %hwnd = $dll(nHTML,find,ThisIsMyLameBox)

echo -a $dll(nHTML,attach,%hwnd)

item

This function returns the handle of a dialog item.

Parameters:

If a word begins with the ‘d’ character, the next number is treated as the dialog handle (default). If a word begins with the ‘i’ character, the next number is treated as the item id.

Return values:

The handle of the dialog item, otherwise E_INVALID_WINDOW or E_INVALID_ID.

Remarks:

This function may not work with future versions of mIRC. Use it only if you must attach a browser to an item without a caption, like a list or combo box. For other controls, consider using the ‘find’ function.

Examples:

This code attaches a browser to a list box:

dialog table {

…

list 10, 5 5 200 200

…

}

…

dialog –md my table

…

var %hwnd = $dll(nHTML,item,$dialog(@my).hwnd id:10)

if (E* !iswm %hwnd) { echo -a $dll(nHTML,attach,%hwnd) }

Just like with the ‘margins’ function, you can freely mix “d” and “i” specifiers:

var %hwnd = $dll(nHTML,item,id = 10 dialog = $dialog(@my).hwnd)

var %hwnd = $dll(nHTML,item,d <<<<==== $dialog(@my).hwnd i <<<===== 10)

handler

This function designates an event handler for the default browser.

Parameter:

The name of an alias.

Return values:

E_INVALID_WINDOW

S_OK

Remarks:

Several browsers can have the same handler.

When mIRC executes the alias, the handle of the browser’s parent window is stored in parameter $1. Parameter $2 holds the name of the event:

navigate_begin	– browser is about to navigate to a URL
state_change	– state of “Back” and “Forward” buttons changes
navigate_complete	– browser has navigated to a URL
document_complete	– document has been downloaded
window_open	– new Internet Explorer is about to open
download_begin	– browser is about to start downloading
progress_change	– download progress changes
download_complete	– browser has finished downloading
status_change	– status bar text has changed
title_change	– titlebar text has changed
visibility_change	– visibility has changed (untested)

Parameters $3- are event-specific.

Normally you should return S_OK from your alias. You can halt the ‘navigate_begin’ and ‘window_open’ events if you return S_CANCEL. If you return anything not beginning with the ‘S’ the browser will stop firing events. To resume event processing, call the ‘handler’ function again.

If you use the ‘select’ function in your alias remember to restore the original selection.

Be careful writing an event handler. It returns control to the browser that triggered the event, therefore the alias must not destroy the browser by detaching it, closing its parent window or unloading the DLL. The alias should be as small and fast as possible. It is recommended that you simply set some flags and return S_OK or S_CANCEL, performing other actions elsewhere.

nHTMLn events are only fired under mIRC 5.9 and newer.

Examples:

This code attaches a browser to a window and sets the “nHTMLn.handler” as its event handler.

window -p @test

echo -a $dll(nHTMLn,attach,$window(@test).hwnd)

echo -a $dll(nHTMLn,handler,nHTMLn.handler)

alias nHTMLn.handler {

echo -a browser = $dll(nHTMLn,caption,$1) $2-

return S_OK

}

This code forbids opening new windows:

window -p @test

echo -a $dll(nHTMLn,attach,$window(@test).hwnd)

echo -a $dll(nHTMLn,handler,nHTMLn.handler)

echo -a $dll(nHTMLn,navigate,www.mircscripts.org/board)

alias nHTMLn.handler {

if ($2 == new_window) { return S_CANCEL }

return S_OK

}

This code makes the default browser stop firing events:

echo -a $dll(nHTMLn,handler,!)

ready

This function tells you if a browser has finished its work and is ready to accept new commands.

Parameter:

The handle of a window with a browser attached. If the handle is invalid, the default browser is used.

Return values:

E_INVALID_WINDOW

E_FAILED

S_TRUE

S_FALSE

Examples:

The code below echoes “done” when www.atptennis.com gets downloaded:

echo -a $dll(nHTMLn,attach,$window(-3).hwnd)

timerwait 0 1 checkatp

echo -a $dll(nHTMLn,navigate,www.atptennis.com)

alias checkatp {

if (S_FALSE != $dll(nHTMLn,ready,$window(-3).hwnd)) {

echo -a done

timerwait off

}

zoom

This function changes the font size in the default browser.

Parameter:

A number in range 0 – 4, where 0 is the smallest font, 4 is the largest.

Return values:

E_INVALID_WINDOW

E_FAILED

E_NOT_READY

S_OK

Remarks:

You can only use this function after the document has been downloaded completely.

Examples:

The code below selects the smallest possible font for www.mirc.com:

window -p @test

echo -a $dll(nHTMLn,attach,$window(@test).hwnd)

echo -a $dll(nHTMLn,handler,nHTMLn.handler)

echo -a $dll(nHTMLn,navigate,www.mirc.com)

alias nHTMLn.handler {

if ($1-2 == $window(@test).hwnd document_complete) {

var %old_hwnd = $dll(nHTMLn,selected,0)

echo -a $dll(nHTMLn,select,$window(@test).hwnd)

echo -a $dll(nHTMLn,zoom,0)

echo -a $dll(nHTMLn,select,%old_hwnd)

}

return S_OK

}

print

This function prints a web page.

Parameter:

The handle of the window with a browser attached. If the handle is invalid, the default browser is used.

Return values:

E_INVALID_WINDOW

E_FAILED

E_NOT_READY

S_OK

Remarks:

You can only use this function after the document has been downloaded completely.

Examples:

This code prints www.mirc.com:

window -pnh @test

echo -a $dll(nHTMLn,attach,$window(@test).hwnd)

echo -a $dll(nHTMLn,handler,myalias)

echo -a $dll(nHTMLn,navigate,www.mirc.com)

alias myalias {

if ($1-2 == $window(@test).hwnd document_complete) {

echo -a $dll(nHTMLn,print,$window(@test).hwnd)

window -c @test

}

return S_OK

}

cursor

This function changes the shape of the mouse cursor.

Parameter:

The number of a standard system cursor, valid ranges on Windows 98SE are 32512-32516 and 32642-32662.

Return values:

E_INVALID_CURSOR

S_OK

Remarks:

You can change the cursor to indicate that a document is being downloaded.

The cursor is a shared resource, you should not change it when it’s not over your window.

Example:

The code below turns the cursor into “hand”:

echo -a $dll(nHTMLn,cursor,32649)

capture, release

The ‘capture’ function directs all the mouse events to a window. The ‘release’ function releases the capture.

Parameter:

‘capture’:

the handle of the window that will capture the mouse input

‘release’:

none

Return values:

E_INVALID_WINDOW

S_OK

Remarks:

Once a window has captured the mouse input it starts to receive ALL mouse events, even if the cursor is outside its boundaries.

Examples:

The code below displays a browser inside a picture window and allows the user to drag it:

alias test {

window -pd @t

dll nHTMLn attach $window(@t).hwnd

dll nHTMLn margins 80

}

menu @t {

sclick {

set -u99999 %x $window(@t).x - $mouse.dx

set -u99999 %y $window(@t).y - $mouse.dy

dll nHTMLn capture $window(@t).hwnd

dll nHTMLn cursor 32646

}

uclick: dll nHTMLn release

mouse {

if ($mouse.key & 1) {

window -pr @t $calc(%x + $mouse.dx) $calc(%y + $mouse.dy) $window(@t).w $window(@t).h

}

else { dll nHTMLn cursor 32649 }

}

version

This function returns information about the DLL and its author.

Parameter:

Ignored.

Example:

var %version = $gettok($dll(nHTMLn,version,0),2,32)

if (%version < 2.9) { echo -a old version of nHTMLn }

#mIRC @ Undernet, necroman@wot.net, necroman@europe.com, necr0man@mail.ru